TRANSACTIONS PLUGIN
--------------------
Authors: Mike Barlow


INTRODUCTION
-------------

A transactions plugin used to easily take payments and keep a record of all the transactions (and the transaction items) taken place.


FEATURES
---------

Take payments from clients
Transactions list for front end / my account section and tab for transactions by user in the admin
Simple to setup new gateways
Refund option
- Doesn't interface with gateways, only for local tracking. User would have to refund via (for example) sagepay admin, then login and refund the transaction on their site.


REQUIREMENTS
-------------

You will need to make sure you have the latest version of core which has the admin users add / edit functionality running through our scaffolding system.



CURRENT GATEWAYS SUPPORTED
---------------------------

Sagepay Server
Stripe
Manual Payment


INSTALLATION
-------------

1) This is a composer plugin so from www/app just run composer as:-

	composer require evoluted/transactions

   You will also need to install Omnipay:-

	composer require omnipay/omnipay

   This will install all of the Omnipay library, you probably just want to include the gateway you intend to use. For example, for Sagepay run:-

	composer require omnipay/sagepay

2) Add the following code to the app/Config/bootstrap.php plugin load array.

'Transactions'=>array(
	'routes' => true,
	'bootstrap' => true
)

3) To setup the database use the CakeDC Migrations plugin. To run the migrations and setup the database run:-

	Console/cake Migrations.migration run all --plugin Transactions

   You may need to setup some additional tables depending on the payment gateway you intend to use. The SQL scripts for these are found in the plugin's _assets folder. For example Sagepay Server requires an extra table.


4) On the User model, place the following relationship.

	public $hasMany = array(
		'Transaction' => array(
			'className' => 'Transactions.Transaction',
			'foreignKey' => 'model_id',
			'conditions' => array(
				'model' => 'User'
			)
		)
	);

4a) If you wish to link a transaction to specific models, e.g. you may want to link the transaction to an order. Copy the following relationship to each of those models, switching out the correct model name.

	public $hasOne = array(
		'Transaction' => array(
			'className' => 'Transactions.Transaction',
			'foreignKey' => 'model_id',
			'conditions' => array(
				'Transaction.model' => 'MODELNAME'
			)
		)
	);

4b) If you wish to link a transaction item to a specific model, e.g. could link each transaction item to each order item row. Copy the following relationship to each of those models, switching out the correct model name.

	public $hasOne = array(
		'TransactionItem' => array(
			'className' => 'Transactions.TransactionsItem',
			'foreignKey' => 'model_id',
			'conditions' => array(
				'TransactionsItem.model' => 'MODELNAME'
			)
		)
	);

4c) If you are going to be making use of the "My Transactions" listing page or the "Transaactions" tab on the user edit screen in the admin, make sure you setup the Transaction to Model relationship in the config file
as described in step 6.


5) Any controller where a transaction will be taking place, add the following component:

	public $components = array(
		'Transactions.Transactions'
	);

6) The plugin has been setup using the standard bootstrap file and code found on the dev wiki. Meaning you can override some config options by placing a config file in the following location: app/Config/Plugin/transactions.php
Available options are:

'gateway' - The gateway to use, this is a snake cased version of the component name minus the word 'component'. I.E. SagepayServerComponent -> sagepay_server
		  - The value of this is also used as the 'key' value for element in the config containing settings for that gateway.

'currency' - The currency to use, this could vary depending on the gateway, default value is 'gbp'

'transaction_relation' - This is an array containing all the possible 'hasOne' relationships the transaction could have. This is used to connect the polymorphic model / model_id values on the transaction
					   - to the order or booking table. Used so we can get the related data on the transaction listing page.
					   - With it being polymorphic, multiple 'hasOne' relationships can be setup here if you are taking payments for multiple things on one site, such as membership renewals and bookings
					   - for events.

'transactions_item_relation' - This is an array containing all the possible 'hasOne' relationships the transaction item could have. This is used to connect the polymorphic model / model_id values on the
							 - transaction item to the order items or booking item table. Used so we can get the related data on the transaction listing page.
						   	 - With it being polymorphic, multiple 'hasOne' relationships can be setup here if you are taking payments for multiple things on one site, such as membership renewals and bookings
						   	 - for events.

'listing' - This is an array containing the details needed to generate the transaction listing page on front end or in the user edit tab.
	- 'contain' - array of Models to contain and bring in on the listing. Models will be contained from the Transaction Model, so choose models you have specified in the 'transaction_relation' array.
	- 'page_id' - Page id to bring in page title / intro text on the front end "My Transactions" page.
	- 'display_field' - A 'Model' => 'fieldname' type array, used to get a name for each of the transaction rows. So you could display the product name or event name if you are taking bookings.
					  - If no options are specified for this, it will attempt to fallback on description fields from the TransactionsItem model to generate the display field.


Other options in the config file should be the settings for each gateway as mentioned in the 'gateway' option details.
For template configuration arrays for each gateway check the _assets/gateway_configs folder.
In most cases there should be a dev / live sub array for each gateway, the gateway component itself should handle the switching of dev / live based of settings from the main app bootstrap file.

An example config file can be found in Transactions/Config/config_example.php

7) Once gateway information is setup you should be ready to take payments!


FUTURE
-------

More components coded for different gateways.

